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Abstract 


Information about which entities are authorized to perform what operations on which 
constituents of other entities is a crucial component of producing an overall system that is 
secure. Conveying precise authorization information is especially critical in highly automated 
systems with large numbers of entities, such as the Internet of Things. 


This specification provides a generic information model and format for representing such 
authorization information, as well as two variants of a specific instantiation of that format for 
use with Representational State Transfer (REST) resources identified by URI path. 
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1. Introduction 


Constrained devices, as they are used in the Internet of Things, need security in order to operate 
correctly and prevent misuse. One important element of this security is that devices in the 
Internet of Things need to be able to decide which operations requested of them should be 
considered authorized, ascertain that the authorization to request the operation does apply to 
the actual requester as authenticated, and ascertain that other devices they make requests of are 
the ones they intended. 


To transfer detailed authorization information from an authorization manager (such as an ACE- 
OAuth authorization server [RFC9200]) to a device, a compact representation format is needed. 
This document defines such a format -- the Authorization Information Format (AIF). AIF is 
defined both as a general structure that can be used for many different applications and as a 
specific instantiation tailored to REST resources and the permissions on them, including some 
provision for dynamically created resources. 


1.1. Terminology 


This memo uses terms from the Constrained Application Protocol (CoAP) [RFC7252] and the 
Internet Security Glossary [RFC4949]; CoAP is used for the explanatory examples as it is a good fit 
for constrained devices. 


The shape of data is specified in Concise Data Definition Language (CDDL) [RFC8610] [RFC9165]. 
Terminology for constrained devices is defined in [RFC7228]. 


The term "byte", abbreviated by "B", is used in its now customary sense as a synonym for "octet". 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 
NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to 
be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in 
all capitals, as shown here. 


2. Information Model 


Authorizations are generally expressed through some data structures that are cryptographically 
secured (or transmitted in a secure way). This section discusses the information model 
underlying the payload of that data (as opposed to the cryptographic armor around it). 


The semantics of the authorization information defined in this document are that of an allow-list: 
everything is denied until it is explicitly allowed. 


For the purposes of this specification, the underlying access control model will be that of an 
access matrix, which gives a set of permissions for each possible combination of a subject and an 
object. We are focusing the AIF data item on a single row in the access matrix (such a row has 
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often been called a "capability list") without concern to the subject for which the data item is 
issued. As a consequence, AIF MUST be used in a way that the subject of the authorizations is 
unambiguously identified (e.g., as part of the armor around it). 


The generic model of such a capability list is a list of pairs of object identifiers (of type Toid) and 
the permissions (of type Tperm) that the subject has on the object(s) identified. 


AIF-Generic<Toid, Tperm> = [* [Toid, Tperm]] 


Figure 1: Definition of Generic AIF 


In a specific data model (such as the one specified in this document), the object identifier (Toid) 
will often be a text string, and the set of permissions (Tperm) will be represented by a bit set, 
which in turn is represented as a number (see Section 3). 


AIF-Specific = AIF-Generic<tstr, uint> 


Figure 2: Commonly Used Shape of a Specific AIF 


2.1. REST-Specific Model 


In the specific instantiation of the REST resources and the permissions on them, we use the URI 
of a resource on a CoAP server for the object identifier (Toid). More specifically, since the parts of 
the URI that identify the server ("authority" in [RFC3986]) are authenticated during REST 
resource access (Section 4.2.2 of [RFC9110] and Section 6.2 of [RFC7252)]), they naturally fall into 
the realm handled by the cryptographic armor; we therefore focus on the "path" ("path- 
abempty") and "query" parts of the URI (URI-local-part in this specification, as expressed by the 
Uri-Path and Uri-Query options in CoAP). As a consequence, AIF MUST be used in a way that it is 
clear who is the target (enforcement point) of these authorizations (note that there may be more 
than one target that the same authorization applies to, e.g., in a situation with homogeneous 
devices). 


For the permissions (Tperm), we use a simple permissions model that lists the subset of the REST 
(CoAP or HTTP) methods permitted. This model is summarized in Table 1. 


URI-local-part Permission Set 
/s/temp GET 

/a/led PUT, GET 

/dtls POST 


Table 1: An Authorization Instance in the 
REST-Specific AIF Information Model 
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In this example, a device offers a temperature sensor /s/temp for read-only access, a LED 
actuator /a/led for read/write, and a /dtls resource for POST access. 


As shown in the data model (Section 3), the representations of REST methods provided are 
limited to those that have a CoAP method number assigned; an extension to the model may be 
necessary to represent permissions for exotic HTTP methods. 


2.2. Limitations 


This simple information model only allows granting permissions for statically identifiable 
objects, e.g., URIs for the REST-specific instantiation. One might be tempted to extend the model 
towards URI templates [RFC6570] (for instance, to open up an authorization for many parameter 
values as in /s/temp{?any*}). However, that requires some considerations of the ease and 
unambiguity of matching a given URI against a set of templates in an AIF data item. 


This simple information model also does not allow expressing conditionalized access based on 
state outside the identification of objects (e.g., "opening a door is allowed if it is not locked"). 


Finally, the model does not provide any special access for a set of resources that are specific to a 
subject, e.g., that the subject created itself by previous operations (PUT, POST, or PATCH/iPATCH 
[RFC8132]) or that were specifically created for the subject by others. 


2.3. REST-Specific Model with Dynamic Resource Creation 


The REST-specific model with dynamic resource creation addresses the need to provide defined 
access to dynamic resources that were created by the subject itself, specifically, a resource that is 
made known to the subject by providing Location-* options in a CoAP response or using the 
Location header field in HTTP [RFC9110] (the Location-indicating mechanisms). (The concept is 
somewhat comparable to "Access Control List (ACL) inheritance" in the Network File System 
version 4 (NFSv4) protocol [RFC8881], except that it does not use a containment relationship but 
rather the fact that the dynamic resource was created from a resource to which the subject had 
access.) In other words, it addresses an important subset of the third limitation mentioned in 
Section 2.2. 


URI-local-part Permission Set 


/a/make-coffee POST, Dynamic-GET, Dynamic-DELETE 


Table 2: An Authorization Instance in the REST-Specific AIF 
Information Model with Dynamic Resource Creation 


For a method X, the presence of a Dynamic-X permission means that the subject holds 
permission to exercise the method X on resources that have been returned in a 2.01 (201 Created) 
response by a Location-indicating mechanism to a request that the subject made to the resource 
listed. In the example shown in Table 2, POST operations on /a/make-coffee might return the 
location of a resource dynamically created on the coffee machine that allows GET to find out 
about the status of, and DELETE to cancel, the coffee-making operation. 
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Since the use of the extension defined in this section can be detected by the mentioning of the 
Dynamic-X permissions, there is no need for another explicit switch between the basic and the 
model extended by dynamic resource creation; the extended model is always presumed once a 
Dynamic-X permission is present. 


3. Data Model 


Different data model specializations can be defined for the generic information model given 
above. 


In this section, we will give the data model for simple REST authorization as per Sections 2.1 and 
2.3. As discussed, in this case the object identifier is specialized as a text string giving a relative 
URI (URI-local-part as the absolute path on the server serving as the enforcement point). The 
permission set is specialized to a single number REST-method-set by the following steps: 


e The entries in the table that specify the same URI-local-part are merged into a single entry 
that specifies the union of the permission sets. 


° The (non-dynamic) methods in the permission sets are converted into their COAP method 
numbers, minus 1. 


e Dynamic-X permissions are converted into what the number would have been for X, plus a 
Dynamic-Offset that has been chosen as 32 (e.g., 35 is the number for Dynamic-DELETE as 
the number for DELETE is 3). 


° The set of numbers is converted into a single number REST-method-set by taking two to the 
power of each (decremented) method number and computing the inclusive OR of the binary 
representations of all the power values. 


This data model could be interchanged in the JSON [RFC8259] representation given in Figure 3. 
[["/s/temp",1],["/a/led",5],["/dtls",2]] 


Figure 3: An Authorization Instance Encoded in JSON (40 Bytes) 


In Figure 4, a straightforward specification of the data model (including both the methods from 
[RFC7252] and the new ones from [RFC8132], identified by the method code minus 1) is shown in 
CDDL [RFC8610] [RFC9165]: 
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AIF-REST = AIF-Generic<local-path, REST-method-set> 
local-path = tstr ; URI relative to enforcement point 
REST-method-set = uint .bits methods 
methods = &( 
GET: @ 
POST: 1 
PUT: 2 
DELEVES 3 
FETCH: 4 
PATCH: 5 
iPATCH: 6 
Dynamic-GET: 32; © .plus Dynamic-Offset 
Dynamic-POST: 33; 1 .plus Dynamic-Offset 
Dynamic-PUT: 34; 2 .plus Dynamic-Offset 
Dynamic-DELETE: 35; 3 .plus Dynamic-Offset 
Dynamic-FETCH: 36; 4 .plus Dynamic-Offset 
Dynamic-PATCH: 37; 5 .plus Dynamic-Offset 
Dynamic-iPATCH: 38; 6 .plus Dynamic-Offset 


) 
Dynamic-Offset = 32 


Figure 4: AIF in CDDL 


For the information shown in Table 1 and Figure 3, a representation in Concise Binary Object 
Representation (CBOR) [RFC8949] is given in Figure 5; again, several optimizations and 
improvements are possible. 


83 # array(3) 
82 # array(2) 
67 # text(7) 
2f732f74656d70 # "/s/temp" 
01 # unsigned(1) 
82 # array(2) 
66 # text(6) 
2f612f6c6564 # "/a/led" 
05 # unsigned(5) 
82 # array(2) 
65 # text(5) 
2f64746c73 # "/dtls" 
02 # unsigned(2) 


Figure 5: An Authorization Instance Encoded in CBOR (28 Bytes) 


Note that having chosen 32 as Dynamic-Offset means that all future CoAP methods that are 
registered can be represented both as themselves and in the Dynamic-X variant, but that only the 
dynamic forms of methods 1 to 21 are typically usable in a JSON form [RFC7493]. 
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4. Media Types 


This specification defines media types for the generic information model, expressed in JSON 
(application/aif+json) or in CBOR (application/aif+cbor). These media types have parameters for 
specifying Toid and Tperm; default values are the values "URI-local-part" for Toid and "REST- 
method-set" for Tperm, as per Section 3 of the present specification. 


A specification that wants to use generic AIF with different Toid and/or Tperm is expected to 
request these as media type parameters (Section 5.2) and register a corresponding Content- 
Format (Section 5.3). 


5. IANA Considerations 


5.1. Media Types 


IANA has added the following media types to the "Media Types" registry. The registration entries 
are in the following subsections. 


Name Template Reference 
aiftcbor application/aiftcbor RFC 9237, Section 4 


aiftjson application/aif+json RFC 9237, Section 4 
Table 3: New Media Types 


5.1.1. application/aif+cbor 


Type name: application 
Subtype name: aif+cbor 
Required parameters: N/A 
Optional parameters: 


Toid: 
the identifier for the object for which permissions are supplied. A value from the "Sub- 
Parameter Registry for application/aif+cbor and application/aif+json" subregistry for Toid. 
Default value: "URI-local-part" (RFC 9237). 


Tperm: 
the data type of a permission set for the object identified via a Toid. A value from the "Sub- 
Parameter Registry for application/aif+cbor and application/aif+json" subregistry for 
Tperm. Default value: "REST-method-set" (RFC 9237). 


Encoding considerations: binary (CBOR) 
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Security considerations: Section 6 of RFC 9237 
Interoperability considerations: N/A 
Published specification: Section 4 of RFC 9237 


Applications that use this media type: Applications that need to convey structured 
authorization data for identified resources, conveying sets of permissions. 


Fragment identifier considerations: The syntax and semantics of fragment identifiers is as 
specified for "application/cbor". (At publication of RFC 9237, there is no fragment 
identification syntax defined for "application/cbor".) 


Person & email address to contact for further information: ACE WG mailing list (ace@ietf.org) 
or IETF Applications and Real-Time Area (art@ietf.org) 


Intended usage: COMMON 
Restrictions on usage: N/A 
Author/Change controller: IETF 
Provisional registration: no 


5.1.2. application/aif+json 


Type name: application 
Subtype name: aiftjson 
Required parameters: N/A 
Optional parameters: 


Toid: 
the identifier for the object for which permissions are supplied. A value from the media- 
type parameter subregistry for Toid. Default value: "URI-local-part" (RFC 9237). 


Tperm: 
the data type of a permission set for the object identified via a Toid. A value from the 
media-type parameter subregistry for Tperm. Default value: "REST-method-set" (RFC 9237). 


Encoding considerations: binary (JSON is UTF-8-encoded text) 
Security considerations: Section 6 of RFC 9237 
Interoperability considerations: N/A 


Published specification: Section 4 of RFC 9237 
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Applications that use this media type: Applications that need to convey structured 
authorization data for identified resources, conveying sets of permissions. 


Fragment identifier considerations: The syntax and semantics of fragment identifiers is as 
specified for "application/json". (At publication of RFC 9237, there is no fragment 
identification syntax defined for "application/json".) 


Person & email address to contact for further information: ACE WG mailing list (ace@ietf.org) 
or IETF Applications and Real-Time Area (art@ietf.org) 


Intended usage: COMMON 
Restrictions on usage: N/A 
Author/Change controller: IETF 


Provisional registration: no 


5.2. Registries 


For the media types application/aif+cbor and application/aif+json, IANA has created a subregistry 
within [[ANA.media-type-sub-parameters] for the media-type parameters Toid and Tperm, 
populated with the following: 


Parameter name Description/Specification Reference 
Toid URI-local-part local-part of URI RFC 9237 
Tperm REST-method-set set of REST methods represented RFC 9237 


Table 4: New Media Type Parameters 


The registration policy is Specification Required [RFC8126]. The designated expert will engage 
with the submitter to ascertain whether the requirements of this document are addressed: 


e The specifications for Toid and Tperm need to realize the general ideas of unambiguous 
object identifiers and permission lists in the context where the AIF data item is intended to 
be used, and their structure needs to be usable with the intended media types (application/ 
aif+cbor and application/aif+json) as identified in the specification. 


° The parameter names need to conform to Section 4.3 of [RFC6838], but preferably they are in 
[KebabCase] so they can be easily translated into names used in APIs with popular 
programming languages. 


The designated experts will develop further criteria and guidelines as needed. 


Bormann Standards Track Page 10 


RFC 9237 ACE AIF August 2022 


5.3. Content-Format 


IANA has registered Content-Format numbers in the "CoAP Content-Formats" subregistry, within 
the "Constrained RESTful Environments (CoRE) Parameters" registry [[ANA.core-parameters], as 
follows: 


Media Type Encoding ID Reference 
application/aif+cbor  - 290 REC 9237 
application/aif+json - 291 RFC 9237 


Table 5: New Content-Formats 


Note that applications that register Toid and Tperm values are encouraged to also register 
Content-Formats for the relevant combinations. 


6. Security Considerations 


The security considerations of [RFC7252] apply when AIF is used with CoAP; Section 11.1 of 
[RFC7252] specifically applies if complex formats such as URIs are used for Toid or Tperm. Some 
wider issues are discussed in [RFC8576]. 


When applying these formats, the referencing specification needs to be careful to ensure: 


e that the cryptographic armor employed around this format fulfills the referencing 
specification's security objectives and that the armor or some additional information 
included in it with the AIF data item (1) unambiguously identifies the subject to which the 
authorizations shall apply and (2) provides any context information needed to derive the 
identity of the object to which authorization is being granted from the object identifiers 
(such as, for the data models defined in the present specification, the scheme and authority 
information that is used to construct the full URI), and 

e that the types used for Toid and Tperm provide the appropriate granularity and precision so 
that application requirements on the precision of the authorization information are fulfilled 
and that all parties have the same understanding of each Toid/Tperm pair in terms of 
specified objects (resources) and operations on those. 


For the data formats, the security considerations of [RFC8259] and [RFC8949] apply. 


A plain implementation of AIF might implement just the basic REST model as per Section 2.1. If it 
receives authorizations that include permissions that use the REST-specific model with dynamic 
resource creation (Section 2.3), it needs to either reject the AIF data item entirely or act only on 
the permissions that it does understand. In other words, the semantics underlying an allow-list 
as discussed above need to hold here as well. 
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An implementation of the REST-specific model with dynamic resource creation (Section 2.3) 
needs to carefully keep track of the dynamically created objects and the subjects to which the 
Dynamic-X permissions apply -- both on the server side to enforce the permissions and on the 
client side to know which permissions are available. 
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